ci: adopt Changesets for versioning and publishing by bmuenzenmeyer · Pull Request #855 · nodejs/doc-kit

bmuenzenmeyer · 2026-06-27T03:50:14Z

closes #791 - and a Slack thread

What

Replaces the bespoke package.json-diff publish flow with Changesets, so releases now produce a CHANGELOG.md, git tags, and GitHub Releases — none of which the previous process generated.

How it works now

Contributors add a changeset per PR (node --run changeset) declaring the bump type + summary.
When changesets land on main, changesets/action opens a "Version Packages" PR that bumps the version and writes CHANGELOG.md.
Merging that PR publishes to npm (via the existing npm OIDC trusted publishing — no token), creates the v<x.y.z> git tag, and cuts a GitHub Release.

Changes

package.json — add @changesets/cli + @changesets/changelog-github; add changeset, changeset:version, release scripts.
.changeset/ — config (changelog-github, access: public, baseBranch: main), README, and one bootstrap changeset.
.github/workflows/release.yml (new, replaces publish.yml) — changesets/action@v1.9.0 pinned by SHA; keeps harden-runner, npm OIDC, and the Slack notify. Permissions bumped to contents: write + pull-requests: write.
CONTRIBUTING.md — "Adding a Changeset" and "Releasing" sections.

⚠️ Action required before first publish

The npm trusted-publisher config currently points at publish.yml. Since the workflow was renamed to release.yml, update the trusted publisher's workflow filename in the npm package settings, or the OIDC publish will fail.

Note

release.yml uses egress-policy: audit (not block) on harden-runner — the publish step legitimately reaches many endpoints (npm registry, sigstore provenance, GitHub API, git push, Slack) and a wrong block allowlist would hard-fail releases. The old publish job had no harden-runner at all, so this is still a net gain; it can be tightened to block once a real run reveals the exact endpoint list.

Verification

changeset status validates config + sees the bootstrap changeset.
A throwaway changeset version produced 1.4.1 + a clean CHANGELOG.md (reverted).
lint + format:check pass.

🤖 Generated with Claude Code

Replace the bespoke package.json-diff publish flow with Changesets so releases produce a CHANGELOG.md, git tags, and GitHub Releases. - Add @changesets/cli + @changesets/changelog-github and changeset, changeset:version, and release scripts - Add .changeset config (changelog-github, public access, main base) - Replace publish.yml with release.yml using changesets/action, keeping npm OIDC trusted publishing and the Slack notification - Document the changeset and release flow in CONTRIBUTING.md Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

cursor · 2026-06-27T03:50:20Z

PR Summary

Medium Risk
Changes how npm packages ship and requires updating npm trusted-publisher workflow name; misconfiguration could block releases until OIDC settings match release.yml.

Overview
Replaces the old publish.yml flow (publish when package.json version changes on main) with Changesets for versioning, changelog, tags, and GitHub Releases.

Adds .changeset/ config (GitHub changelog for nodejs/doc-kit, public access, main base branch) plus a bootstrap patch changeset. package.json gains @changesets/cli / @changesets/changelog-github and scripts changeset, changeset:version, and release (changeset publish).

New .github/workflows/release.yml runs changesets/action on every push to main: pending changesets open/update a Version Packages PR; after that merges, it publishes via npm OIDC, tags, and creates a GitHub Release. Keeps Slack notify on publish; adds harden-runner with audit egress (broader than the removed publish job’s blocked list). Job permissions include contents: write and pull-requests: write.

CONTRIBUTING.md documents contributor changesets and the maintainer release path (no manual version bumps).

Before the first publish: npm trusted publishing must reference release.yml instead of publish.yml.

^{Reviewed by Cursor Bugbot for commit 105d54d. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-06-27T03:50:20Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 28, 2026 3:36am

+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Changesets needs full history (and credentials) to push the version branch and tags.
+          fetch-depth: 0


codecov · 2026-06-27T03:50:44Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.99%. Comparing base (8851110) to head (56b213d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #855      +/-   ##
==========================================
- Coverage   84.99%   84.99%   -0.01%     
==========================================
  Files         179      179              
  Lines       16404    16407       +3     
  Branches     1482     1483       +1     
==========================================
+ Hits        13943    13945       +2     
- Misses       2451     2452       +1     
  Partials       10       10

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 105d54d. Configure here.}

cursor · 2026-06-27T03:51:46Z

+          version: node --run changeset:version
+          publish: node --run release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}


Publish verification checks removed

Medium Severity

Replacing publish.yml drops the pre-publish checks that required a GPG-verified commit and a merge-queue committer before any npm publish. The new Release job runs changesets/action (including node --run release) on every push to main with no equivalent authenticity gate on the publish path.

^{Reviewed by Cursor Bugbot for commit 105d54d. Configure here.}

- Add a concurrency group (cancel-in-progress: false) so overlapping pushes to main can't race the version PR push or the publish step - Guard the job with github.repository so forks don't attempt to publish Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

bmuenzenmeyer requested a review from a team as a code owner June 27, 2026 03:50

github-advanced-security AI found potential problems Jun 27, 2026

View reviewed changes

vercel Bot deployed to Preview June 27, 2026 03:51 View deployment

cursor Bot reviewed Jun 27, 2026

View reviewed changes

bmuenzenmeyer marked this pull request as draft June 27, 2026 03:51

use correct hash/version

5a429a1

github-advanced-security AI found potential problems Jun 27, 2026

View reviewed changes

Comment thread .github/workflows/release.yml Fixed

vercel Bot deployed to Preview June 27, 2026 13:15 View deployment

fix lockfile

a893e1a

vercel Bot deployed to Preview June 28, 2026 03:17 View deployment

regenerate lockfile

32994ae

vercel Bot deployed to Preview June 28, 2026 03:23 View deployment

This comment was marked as off-topic.

Sign in to view

fix sha/tag ref

e7553c0

vercel Bot deployed to Preview June 28, 2026 03:29 View deployment

vercel Bot deployed to Preview June 28, 2026 03:36 View deployment

bmuenzenmeyer marked this pull request as ready for review June 29, 2026 15:11

bmuenzenmeyer added the web-agenda label Jul 1, 2026

avivkeller approved these changes Jul 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ci: adopt Changesets for versioning and publishing#855

ci: adopt Changesets for versioning and publishing#855
bmuenzenmeyer wants to merge 6 commits into
mainfrom
changesets

bmuenzenmeyer commented Jun 27, 2026 •

edited

Loading

Uh oh!

cursor Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

codecov Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Jun 27, 2026

Uh oh!

Uh oh!

This comment was marked as off-topic.

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

bmuenzenmeyer commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How it works now

Changes

⚠️ Action required before first publish

Note

Verification

Uh oh!

cursor Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

vercel Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 27, 2026

Choose a reason for hiding this comment

Publish verification checks removed

Uh oh!

Uh oh!

This comment was marked as off-topic.

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bmuenzenmeyer commented Jun 27, 2026 •

edited

Loading

cursor Bot commented Jun 27, 2026 •

edited

Loading

vercel Bot commented Jun 27, 2026 •

edited

Loading

codecov Bot commented Jun 27, 2026 •

edited

Loading